<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Multiword Synonyms and Phrase Queries | Elasticsearch: The Definitive Guide [2.x] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch: The Definitive Guide [2.x]">
<link rel="up" href="synonyms.html" title="Synonyms">
<link rel="prev" href="synonyms-analysis-chain.html" title="Synonyms and The Analysis Chain">
<link rel="next" href="symbol-synonyms.html" title="Symbol Synonyms">
<meta name="DC.type" content="Learn/Docs/Legacy/Elasticsearch/Definitive Guide/2.x">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="2.x">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<p>
  <strong>WARNING</strong>: The 2.x versions of Elasticsearch have passed their
  <a href="https://www.elastic.co/support/eol">EOL dates</a>. If you are running
  a 2.x version, we strongly advise you to upgrade.
</p>
<p>
  This documentation is no longer maintained and may be removed. For the latest
  information, see the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">current
  Elasticsearch documentation</a>.
</p>
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch: The Definitive Guide [2.x]</a></span>
»
<span class="breadcrumb-link"><a href="languages.html">Dealing with Human Language</a></span>
»
<span class="breadcrumb-link"><a href="synonyms.html">Synonyms</a></span>
»
<span class="breadcrumb-node">Multiword Synonyms and Phrase Queries</span>
</div>
<div class="navheader">
<span class="prev">
<a href="synonyms-analysis-chain.html">« Synonyms and The Analysis Chain</a>
</span>
<span class="next">
<a href="symbol-synonyms.html">Symbol Synonyms »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="multi-word-synonyms"></a>Multiword Synonyms and Phrase Queries<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/260_Synonyms/60_Multi_word_synonyms.asciidoc">edit</a>
</h2>
</div></div></div>
<p>So far, synonyms appear to be quite straightforward. Unfortunately, this is
where things start to go wrong. For <a class="xref" href="phrase-matching.html" title="Phrase Matching">phrase queries</a> to
function correctly, Elasticsearch needs to know the position that each term
occupies in the original text. Multiword synonyms can play havoc with term
positions, especially when the injected synonyms are of differing lengths.</p>
<p>To demonstrate, we’ll create a synonym token filter that uses this rule:</p>
<pre class="literallayout">"usa,united states,u s a,united states of america"</pre>

<div class="pre_wrapper lang-json">
<pre class="programlisting prettyprint lang-json">PUT /my_index
{
  "settings": {
    "analysis": {
      "filter": {
        "my_synonym_filter": {
          "type": "synonym",
          "synonyms": [
            "usa,united states,u s a,united states of america"
          ]
        }
      },
      "analyzer": {
        "my_synonyms": {
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "my_synonym_filter"
          ]
        }
      }
    }
  }
}

GET /my_index/_analyze?analyzer=my_synonyms&amp;text=
The United States is wealthy</pre>
</div>
<p>The tokens emitted by the <code class="literal">analyze</code> request look like this:</p>
<div class="pre_wrapper lang-text">
<pre class="programlisting prettyprint lang-text">Pos 1:  (the)
Pos 2:  (usa,united,u,united)
Pos 3:  (states,s,states)
Pos 4:  (is,a,of)
Pos 5:  (wealthy,america)</pre>
</div>
<p>If we were to index a document analyzed with synonyms as above, and then run a
phrase query without synonyms, we’d have some surprising results.  These
phrases would not match:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The usa is wealthy
</li>
<li class="listitem">
The united states of america is wealthy
</li>
<li class="listitem">
The U.S.A. is wealthy
</li>
</ul>
</div>
<p>However, these phrases would:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
United states is wealthy
</li>
<li class="listitem">
Usa states of wealthy
</li>
<li class="listitem">
The U.S. of wealthy
</li>
<li class="listitem">
U.S. is america
</li>
</ul>
</div>
<p>If we were to use synonyms at query time instead, we would see even more-bizarre matches. Look at the output of this <code class="literal">validate-query</code> request:</p>
<div class="pre_wrapper lang-json">
<pre class="programlisting prettyprint lang-json">GET /my_index/_validate/query?explain
{
  "query": {
    "match_phrase": {
      "text": {
        "query": "usa is wealthy",
        "analyzer": "my_synonyms"
      }
    }
  }
}</pre>
</div>
<p>The explanation is as follows:</p>
<pre class="literallayout">"(usa united u united) (is states s states) (wealthy a of) america"</pre>

<p>This would match documents containg <code class="literal">u is of america</code> but wouldn’t match any
document that didn’t contain the term <code class="literal">america</code>.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>Multiword synonyms affect highlighting in a similar way.  A query for <code class="literal">USA</code>
could end up returning a highlighted snippet such as: “The <em>United States
is wealthy</em>”.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_use_simple_contraction_for_phrase_queries"></a>Use Simple Contraction for Phrase Queries<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/260_Synonyms/60_Multi_word_synonyms.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The way to avoid this mess is to use <a class="xref" href="synonyms-expand-or-contract.html#synonyms-contraction" title="Simple Contraction">simple contraction</a>
to inject a single term that represents all synonyms, and to use the same
synonym token filter at query time:</p>
<div class="pre_wrapper lang-json">
<pre class="programlisting prettyprint lang-json">PUT /my_index
{
  "settings": {
    "analysis": {
      "filter": {
        "my_synonym_filter": {
          "type": "synonym",
          "synonyms": [
            "united states,u s a,united states of america=&gt;usa"
          ]
        }
      },
      "analyzer": {
        "my_synonyms": {
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "my_synonym_filter"
          ]
        }
      }
    }
  }
}

GET /my_index/_analyze?analyzer=my_synonyms
The United States is wealthy</pre>
</div>
<p>The result of the preceding <code class="literal">analyze</code> request looks much more sane:</p>
<div class="pre_wrapper lang-text">
<pre class="programlisting prettyprint lang-text">Pos 1:  (the)
Pos 2:  (usa)
Pos 3:  (is)
Pos 5:  (wealthy)</pre>
</div>
<p>And repeating the <code class="literal">validate-query</code> request that we made previously yields a simple,
sane explanation:</p>
<pre class="literallayout">"usa is wealthy"</pre>

<p>The downside of this approach is that, by reducing <code class="literal">united states of america</code>
down to the single term <code class="literal">usa</code>, you can’t use the same field to find just the
word <code class="literal">united</code> or <code class="literal">states</code>. You would need to use a separate field with a
different analysis chain for that purpose.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_synonyms_and_the_query_string_query"></a>Synonyms and the query_string Query<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/260_Synonyms/60_Multi_word_synonyms.asciidoc">edit</a>
</h3>
</div></div></div>
<p>We have tried to avoid discussing the <code class="literal">query_string</code> query because we don’t
recommend using it.  In <a class="xref" href="search-lite.html#query-string-query" title="More Complicated Queries">"More-Complicated Queries"</a>, we said that, because the
<code class="literal">query_string</code> query supports a terse mini <em>search-syntax</em>, it could
frequently lead to surprising results or even syntax errors.</p>
<p>One of the gotchas of this query involves multiword synonyms. To
support its search-syntax, it has to parse the query string to recognize
special operators like <code class="literal">AND</code>, <code class="literal">OR</code>, <code class="literal">+</code>, <code class="literal">-</code>, <code class="literal">field:</code>, and so forth.  (See the full
<a href="/guide/en/elasticsearch/reference/2.4/query-dsl-query-string-query.html#query-string-syntax" class="ulink" target="_top"><code class="literal">query_string</code> syntax</a>
for more information.)</p>
<p>As part of this parsing process, it breaks up the query string on whitespace,
and passes each word that it finds to the relevant analyzer separately. This
means that your synonym analyzer will never receive a multiword synonym.
Instead of seeing <code class="literal">United States</code> as a single string, the analyzer will
receive <code class="literal">United</code> and <code class="literal">States</code> separately.</p>
<p>Fortunately, the trustworthy <code class="literal">match</code> query supports no such syntax, and
multiword synonyms will be passed to the analyzer in their entirety.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="synonyms-analysis-chain.html">« Synonyms and The Analysis Chain</a>
</span>
<span class="next">
<a href="symbol-synonyms.html">Symbol Synonyms »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
